home *** CD-ROM | disk | FTP | other *** search
/ Internet File Formats / InternetFileFormatsCD.bin / text / latex / mac / alpha60.hqx / Help / BibTeX Help < prev    next >
Encoding:
Text File  |  1994-09-23  |  9.2 KB  |  237 lines
  1. ----------------------
  2. BibTeX mode for Alpha
  3. ----------------------
  4.  
  5. This document describes features of Bib mode and the BibTeX menu, 
  6. which were written to simplify the use and maintenance of BibTeX 
  7. citation database files.
  8.  
  9. Bib Mode and the BibTeX menu
  10. ----------------------------
  11.  
  12. Bib mode is entered when you open a file with a '.bib' suffix, or select 
  13. the mode explicitly from the modes menu.  In Bib mode,
  14.  
  15. 1.  A BibTeX menu is added to the menubar.  From this menu, you can:
  16.     (key bindings indicated where available)
  17.  
  18.  Ñ    Launch the BibTeX application.
  19.  
  20.  Ñ    Insert templates for any of the various BibTeX bibliography entry 
  21.     types or data fields.
  22.     
  23.     By default, only the required fields an the entry are included in 
  24.     the template.  This can be customized as described below.
  25.    
  26.  Ñ    Select (highlight) the current entry (in which the cursor sits), 
  27.     allowing the entry to be easily moved, copied or deleted.
  28.     (Ctl-Shift-B)
  29.    
  30.  Ñ    Jump to the next or previous entry.
  31.      (Ctl-Shift-N or Ctl-Shift-P)
  32.    
  33.  Ñ    Reformat the current entry in a standard form, with data fields 
  34.     indented and aligned, and data-field delimiters made uniform.
  35.     Afterwards, Alpha jumps forward to the next entry.
  36.     (Ctl-Shift-L)
  37.    
  38.     The data field indentation is controlled by the "indentString" mode 
  39.     variable in the mode-flags menu.  The "fieldBraces" flag selects curly 
  40.     braces or double-quotes as the data-field delimiter; likewise, the 
  41.     "entryBraces" flag selects curly braces or parentheses as the 
  42.     data-field delimiter.  The "fillColumn" variable controls line-wrapping.
  43.    
  44.  Ñ    Search for entries that match a given regular expression.
  45.      (Ctl-Shift-M)
  46.    
  47.  Ñ    Search for entries in which a particular field matches a regular 
  48.     expression.
  49.     (Ctl-Shift-F)
  50.  
  51.     Entries found in a search will be copied to a new window (the 
  52.     default) or back into the original buffer, replacing the previous 
  53.     contents of the buffer; this is controlled by the "overwriteBuffer" 
  54.     flag in the mode-flags menu.  The contents of a ".bib" file, 
  55.     however, will never be overwritten by a search, since entries are 
  56.     typically lost.
  57.     
  58.  Ñ    Sort the database by cite-key, by first author, or by last author.
  59.  
  60.      The overwriteBuffer flag also controls whether the sorted database 
  61.      is written back to the original buffer or into a new one.  A ".bib" 
  62.      file _can_ be overwritten by a sort, since no entries are lost.
  63.        
  64. 2.  Selecting 'Mark File' in the marks menu, on the sidebar, will 
  65.     add a mark for each entry in the bib file using the cite key of the 
  66.     entry.  These are added in order of appearance in the file, but can 
  67.     subsequently be sorted alphabetically using the "Named Marks:Sort" 
  68.     command under the "Search" menu.
  69.  
  70. 3. Key words in Bib files are automatically colorized.
  71.  
  72.  
  73. Key Bindings
  74. ------------
  75.  
  76. Most of these functions (except template insertion) are also bound to 
  77. keystrokes.  The standard bindings are
  78.  
  79.     Ctl-Shift-N     next entry
  80.     Ctl-Shift-P     previous entry
  81.  
  82.     Ctl-Shift-B     select entry   
  83.     Ctl-Shift-L     format entry
  84.  
  85.     Ctl-Shift-M     search entries
  86.     Ctl-Shift-F     search fields
  87.  
  88.             tab     next tab stop      (as in TeX mode)
  89.       Shift-tab     previous tab stop  ( "  "  "   "  )
  90.         Ctl-tab     nth tab stop       ( "  "  "   "  )
  91.         Cmd-tab     clear tab stop     ( "  "  "   "  )
  92.         
  93.         Opt-tab     insert a tab       ( "  "  "   "  )
  94.  
  95. Although the TeX-mode keybindings aren't available in Bib mode, the 
  96. LaTeX menu is left on the menubar.  This may be useful for inserting the
  97. various text-style codes that are recognized in BibTeX fields. 
  98.  
  99.  
  100. Customizing Entry Templates
  101. ---------------------------
  102.  
  103. As mentioned above, by default only the required fields are included 
  104. when a new bib entry is created.  You can select any other set of fields 
  105. by adding an appropriate entry to the 'myFld' array, following the 
  106. example for the Article entry in the file :UserCode:bibtex.tcl file.  
  107. Some day I'll make it easier to customize this, but for now it's 
  108. necessary to modify bibtex.tcl.
  109.  
  110. You should _not_ change the 'rqdFld' or 'optFld' arrays, since these 
  111. will (some day) be used for syntax checking.
  112.  
  113.  
  114. Bugs, etc.
  115. ----------
  116.  
  117. Bug reports, complaints and suggestions are very welcome.  In 
  118. particular, the code hasn't been tested for a wide variety of BibTeX 
  119. data formats, so I don't know how robust my routines for parsing BibTeX 
  120. entries really are.  Some of my own ideas for additional features and/or
  121. improvements are listed further below.  
  122.  
  123. Comments and bug reports should be directed to
  124.  
  125. Tom Pollard
  126.  
  127. e-mail:            pollard@cucbs.chem.columbia.edu
  128.  
  129. snail-mail:        544 W 114th St #2R
  130.                 New York, NY 10025
  131.                 USA
  132.  
  133.  
  134. Version History
  135. ---------------
  136.  
  137. 2.0 (9/94)    'formatEntry' and 'newEntry' line up fields better.
  138.               'nextEntry' and 'prevEntry' skip @string defs
  139.               'formatEntry' automtically goes to next entry afterwards.
  140.               'sortByCitekey' ignores case of cite keys.
  141.               'fillColumn' included as default modeVar.
  142.               'getEntry' alerts user to badly delimited entries.
  143. 1.9 (9/94)    'getFields' should now correctly parse any legal entry.
  144.               'language' field now included.
  145.               Default values for new fields (eg 'language') may be defined
  146.               'preferBraces' replaced by 'fieldBraces' and 'entryBraces'.
  147.               line-wrapping is done on reformatted entries.
  148.               '@string' entries preserved in sorts.
  149.               text before first entry and after last entry are preserved
  150.                   by sorts.
  151. 1.8 (8/94)    "getEntry" now recognizes parens as entry delimiters
  152. 1.7 (8/94)    Bug fixes and accomodations to latex.tcl v2.2
  153.               Template insertion streamlined
  154.               Choose multiple fields at a time from a list dialog
  155. 1.6 (8/94)    "preferBraces" allows braces or quotes to be default for
  156.                   new or reformatted entries,
  157.               Menu built using $entryNames and $fieldNames,
  158.               'sortByAuthors' can now sort using last author first,
  159.                   and is a bit faster,
  160.               'formatEntry' rewrites entries in canonical format,
  161.               More customization of canonical format allowed ('indentString')
  162.               Bib mode definition adapted to Alpha 5.90.
  163. 1.5 (7/94)    "sortByAuthors" is now robust,
  164.               Mode of new windows now set correctly.
  165. 1.4 (7/94)    Added sorting by authors, but still only semi-functional,
  166.               Added regexp searching by field,
  167.               "getEntry" bugs fixed.
  168. 1.2 (7/94)    Bib mode definition adapted to Alpha 5.85,
  169.               Added bib-file marking (bibMarkFile),
  170.               Entry and field creation now controlled by data arrays.
  171. 1.1 (6/94)    Custom BibTeX icon, 
  172.               Added simple search capability (matchingEntries).
  173. 1.0 (9/93)    First stable version.
  174.  
  175.  
  176. Possible Future Enhancements
  177. ----------------------------
  178.  
  179. 1.    Sorting by other fields.  Specifically, I'd like to have it
  180.     sort by date, by first author and date, or by last author and date.
  181.     
  182. 2.    Allowing more customization of the 'standard' entry format used for
  183.     new entries and the 'Format Entry' command.   
  184.     
  185. 3.  Allowing the user to interactively choose the standard fields used 
  186.     for a given entry type.
  187.     
  188. 4.    Tighter integration with TeX mode; for instance, automatically 
  189.     opening the .bib files for a document by scanning the '\bibliography{}'
  190.     command(s) in the document, and allowing single-keystroke jumps from a 
  191.     citation ('\cite{}') to the corresponding database entry.  An easy way 
  192.     to paste cite keys into a TeX document might be nice, but I don't know 
  193.     what the most convenient way to do that would be.
  194.     
  195. 5.  Allowing more complicated searches.  Logical 'AND' searches can be 
  196.     done now by doing additional searches on the results of previous ones.  
  197.     It would be nice to allow logical 'OR' searches by concatenating the 
  198.     results of successive searches to a database in the same buffer.  Ideas 
  199.     for simple, intuitive ways to control this would be welcome.
  200.  
  201. 6.    Some sort of consistency and/or syntax checking of the database; for
  202.     instance, verifying that all entries have the required fields and 
  203.     checking for duplicate entries.
  204.  
  205. ?.  Since the code parses BibTeX entries already, it would be easy to 
  206.     export .bib files to other formats, but I'm not sure if it's a good idea 
  207.     to start burdening Alpha with that sort of thing.  Writing Perl scripts 
  208.     for file conversions is probably a better route.  See, for instance, the 
  209.     "CC to BibTeX" Perl script (included in the :Tcl:UserCode:TextFilters 
  210.     folder), which converts citations from the on-line Current Contents 
  211.     database (the one at UC Berkeley, anyway) to BibTeX format.  
  212.  
  213.  
  214. BibTeX application
  215. ------------------
  216.  
  217. If you don't already have a BibTeX application, version 2.0 of MacBibTeX
  218. is available, among other places, from
  219.  
  220.     ftp.bluesky.com    (198.145.40.2)        pub/utilities/BibTeX.sea.hqx
  221.  
  222. It was written by
  223.  
  224.     Jim Studt        <jim@wucs1.wustl.edu>   , and
  225.     Michael Kahn    <kahn@wucs1.wustl.edu>
  226.     
  227. based on Oren Patashnik's original BibTeX 0.99c .
  228.  
  229. Acknowledgments:
  230. ----------------
  231.  
  232. This package was inspired by LaTeX support package (latex.tcl), written by
  233.  
  234.    Richard T. Austin  <austin@eecs.umich.edu>  , and (currently),
  235.    Tom Scavo          <trscavo@syr.edu>
  236.    
  237. ---------------------------------------------------------------------------